home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Programmer Disk
/
The Programmer Disk (Microforum).iso
/
xpro
/
c3
/
pro21
/
source.doc
< prev
next >
Wrap
Text File
|
1992-10-13
|
97KB
|
2,076 lines
SOURCE
Version 1.01
October 14, 1992
Written by
Rick Maddy
SOURCE Table of Contents
1 Distribution . . . . . . . . . . . . . . . . . . . . Page 1
2 What is SOURCE? . . . . . . . . . . . . . . . . . . Page 1
3 Quick Start . . . . . . . . . . . . . . . . . . . . Page 2
4 The SOURCE Command Line . . . . . . . . . . . . . . Page 3
4.1 Global Options . . . . . . . . . . . . . . . . Page 3
4.2 Filenames . . . . . . . . . . . . . . . . . . . Page 4
4.3 Local Options . . . . . . . . . . . . . . . . . Page 5
4.4 Full Command Line . . . . . . . . . . . . . . . Page 5
5 SOURCE Options . . . . . . . . . . . . . . . . . . . Page 5
6 SOURCE.CFG . . . . . . . . . . . . . . . . . . . . . Page 16
6.1 SOURCE.CFG Location . . . . . . . . . . . . . . Page 16
6.2 Named Configuration Options . . . . . . . . . . Page 16
6.3 SOURCE.CFG Format . . . . . . . . . . . . . . . Page 17
6.4 Commenting SOURCE.CFG . . . . . . . . . . . . . Page 18
6.5 Modifying SOURCE.CFG . . . . . . . . . . . . . Page 18
7 SOURCE.PRT . . . . . . . . . . . . . . . . . . . . . Page 18
7.1 Default Printer . . . . . . . . . . . . . . . . Page 18
7.2 SOURCE.PRT Format . . . . . . . . . . . . . . . Page 19
7.3 Modifying Your Printer . . . . . . . . . . . . Page 23
8 SOURCE.LNG . . . . . . . . . . . . . . . . . . . . . Page 23
8.1 SOURCE.LNG Location . . . . . . . . . . . . . . Page 23
8.2 SOURCE.LNG Format . . . . . . . . . . . . . . . Page 24
8.3 Commenting SOURCE.LNG . . . . . . . . . . . . . Page 25
8.4 Defining Language Specific Features . . . . . . Page 25
8.4.1 Comments . . . . . . . . . . . . . . Page 25
8.4.2 String and Character Literals . . . . Page 26
8.4.3 Blocks . . . . . . . . . . . . . . . Page 27
8.4.4 Keywords . . . . . . . . . . . . . . Page 28
8.4.5 Complete Definition . . . . . . . . . Page 28
8.5 General Points . . . . . . . . . . . . . . . . Page 30
9 Network Support . . . . . . . . . . . . . . . . . . Page 30
10 Definition of Shareware . . . . . . . . . . . . . . Page 31
11 Disclaimer - Agreement For Trying SOURCE . . . . . . Page 31
12 Registering . . . . . . . . . . . . . . . . . . . . Page 32
13 Future Enhancements . . . . . . . . . . . . . . . . Page 33
14 Acknowledgements . . . . . . . . . . . . . . . . . . Page 33
SOURCE REGISTRATION . . . . . . . . . . . . . . . . . . . Page 34
Page i
SOURCE
SOURCE Version 1.01 - Source code file printing utility
Copyright 1992 Rick Maddy
1 Distribution
The SOURCE program is made up of these files:
SOURCE.EXE The SOURCE program file.
SOURCE.DOC This documentation file.
SOURCE.PRT The default printer definition file.
SOURCE.CFG The default configuration option file.
SOURCE.LNG The default language definition file.
README.1ST Quick summary and last minute notes.
REGISTER.TXT Order form to register SOURCE.
This unregistered shareware program is distributed in the PKZIP
format. SOURCE.ZIP may be passed onto as many people as you
like, provided it remains intact, ALL files are kept together,
and only the original files are distributed. DO NOT zip up and
pass on your modified files. See section 10 below for further
information on shareware.
2 What is SOURCE?
SOURCE, in its most basic form, is a program for printing source
code and text files. However, using SOURCE to its fullest
potential gives you an extremely powerful and flexible program
for printing source code and allows for numerous options for
formatting the output:
- Custom page sizing
- Adjustable margins
- Page orientation (portrait or landscape)
- Character pitch (pica, elite, or compressed)
- Number of columns per page
- User definable page header/footers
- Optional banner page before/after files
- Output may be redirected to any device or file
- Printing ranges may be specified, including starting
and/or ending line or page numbers
- Multiple files can be queued for printing
In addition to these basic printing options, SOURCE contains many
options specifically geared toward formatting source code (such
as C, Pascal, Fortran, dBase, or whatever you code in). These
include:
- User definable line and page numbering
- Comments in the source code may be printed as bold,
italic, or underlined
- Keywords may be highlighted
- Code blocks grouped graphically
- Adjustable tab sizes for printing
- Configurable language support
Page 1
SOURCE
These are just some of the powerful options available to you.
Yet, SOURCE is very easy to use. SOURCE only needs to know the
name of the file(s) you wish to print and it does the rest. You
can use SOURCE right out of the box (so to speak).
For example:
C:\> SOURCE kludge.c
This would print your file to the default printer using the built
in defaults.
You may configure each option to suit your needs. See section 5
for a complete list of all the options. Besides the printing
options, SOURCE is extremely flexible in its ability to work with
almost any printer and most programming languages.
To facilitate this dynamic environment, SOURCE consists of an
executable (SOURCE.EXE) and three support files:
SOURCE.PRT: Contains all the printer definitions.
SOURCE.CFG: Contains all the default options used by
SOURCE to print your files.
SOURCE.LNG: Contains all the language and filename
extension specifications needed for comment
and keyword highlighting and block grouping.
By default, all four files that make up SOURCE are named
"SOURCE.???" where '???' is "EXE", "PRT", "CFG", and "LNG". If
you prefer to use a different name, such as "SRC", instead of
"SOURCE", simply rename all four files to the same prefix.
Example:
C:\>ren source.* src.*
This will result in all four files having the "SRC.???" name
instead of "SOURCE.???". Anywhere in this documentation you are
to execute "SOURCE", enter "SRC" instead. The only advantage to
this is to save on typing "SOURCE" all the time, noe you enter
"SRC". You could even change all the names to "S" if you really
like terse, UNIX-like command names.
3 Quick Start
Before running SOURCE for the first time (as if you have read
this far without having already done so), make sure you have
placed SOURCE.EXE, SOURCE.PRT, SOURCE.LNG, and SOURCE.CFG all
within the same directory. You may also wish to include this
directory in your path so that you can run SOURCE from anywhere
on your system. If you need more information on PATHs, see your
DOS manual.
The simplest way of running SOURCE is to type:
SOURCE filename.ext
Page 2
SOURCE
"SOURCE" is the program SOURCE and "filename.ext" is the name of
the file you are going to print. You may press the [Esc] key
anytime while a file is printing to abort SOURCE and stop the
current file from printing. Remember, most printers have buffers
and the printing will probably not stop immediately.
The first time you run SOURCE you will be asked to select your
default printer. This printer should be the one connected to
printer port one, "LPT1:". If you are using a different port,
see section 6 for information on changing the printer port used
by SOURCE. The list of printers initially supported by SOURCE
contains printers which should cover most of the printers in use.
Pick the printer that closest matches the one you have.
Note: If none of the printers are like yours, select
the "Generic" printer for now. You will still be able
to print files, you just won't be able to take full
advantage of SOURCE's strengths. Later on you'll see
how to modify SOURCE.PRT to take full advantage of your
printer. See section 7 for more information on printer
definitions.
Typing "SOURCE" at the prompt with no options will give you a few
lines about the general command line syntax. You may type
"SOURCE -?" to see a few screens showing the command line syntax,
what each option is, and the options' current defaults. After
the options, you will be shown what printers, languages, and
named configuration options are defined in the SOURCE.PRT,
SOURCE.LNG, and SOURCE.CFG files.
4 The SOURCE Command Line
SOURCE is a command line utility. To run SOURCE, type the name
of this program, SOURCE, followed by any options you wish to use
along with the filename(s) of the file(s) you wish to print. The
command line syntax is as follows:
SOURCE [-global options] filename.ext [-local options] . . .
Objects in square brackets are optional and the ". . ." means you
may repeat as many filenames as you wish to have printed.
The command line has two levels of options, global and local.
Global options are configuration options that apply to all files
on the command line. Local options only apply to the files that
immediately precede them.
4.1 Global Options
Global options appear after the program name and before the first
filename. These options apply to all the files specified on the
command line. Global parameters are optional. The syntax of
global options is a hyphen ( - ) followed by a one letter option
followed by any required parameters. Options that take
parameters require that there be no space between the option and
Page 3
SOURCE
the parameter. String parameters are slightly different. A
space before the parameter is allowed. String parameters may
also be enclosed in double quotes. The quotes are required only
if the string contains spaces. An example is:
SOURCE -n -N4 -r com1
The above example only contains global options (in this case,
four digit line numbers with output redirected to comm port one).
This example will not actually produce any output because no
files are specified yet.
Options that you use frequently can be permanently preset within
the SOURCE.CFG file. This way, you do not have to specify them
each time you use SOURCE. See section 6 for a discussion on
setting global options as defaults.
4.2 Filenames
After the global parameters, if any, you may specify the files
you wish to print. In the simplest form, this would be a single
filename and its extension.
SOURCE foobar.c
Running this would cause SOURCE to print the file "foobar.c" from
the current directory. To specify a file in another directory or
on another disk drive, use the full path name, as in the example
below:
SOURCE c:\src\code.pas
This would print the file "code.pas" found in the "c:\src\code"
directory despite your current working directory.
There are three methods for printing multiple files. The most
tiresome is to run SOURCE once for each file you need to print.
The second option is to use wildcards when specifying the
filename. The wildcards allowed are '*' and '?'. These behave
exactly like the wildcards used by DOS commands (such as copy and
delete). If you do not understand how wildcards work, please
refer to your DOS manual for more information. An example of
wildcard use is:
SOURCE *.c
This would cause SOURCE to print all files in the current
directory that had the extension ".c". Each file will be printed
separately, starting on page one, line one.
The third method for printing multiple files is to enter more
than one name on the command line:
SOURCE program.c data.txt
Page 4
SOURCE
This would cause SOURCE to print the two files, "program.c" and
"data.txt", from the current directory. You may specify as many
files as the command line has room for.
Any combination of these methods may used, for example:
SOURCE *.c b:*.txt c:\proj\*.*
This command line would print all 'C' files in the current
directory, all files with the extension ".txt" from the disk in
the B drive, and all files from the "proj" directory of the C
drive.
4.3 Local Options
In addition to the global options, you may specify "local"
options after each filename. These local options override the
global options and only apply to the file they immediately follow
on the command line. Local options are optional. The syntax for
local options is identical to that of global options (see section
4.1). Example:
SOURCE -n hello.c goodbye.c -n-
This command will cause SOURCE to print the file "hello.c" from
the current directory with line numbers and "goodbye.c" without
line numbers. The global option "-n" causes line numbering to be
turned on for all files. Specifying "-n-" after "goodbye.c"
tells SOURCE to turn line numbering off only for "goodbye.c" and
does not affect "hello.c". Local options used after filenames
with wildcards will apply to all the files matched by the
wildcards:
SOURCE *.c -b -c
will print all 'C' files with block tracing and highlighted
comments turned on for each file. This also shows that you may
specify more than one local option per file. Of course, you do
not have to specify any local options if they are not needed.
4.4 Full Command Line
The command line for SOURCE is very flexible. This flexibility
can also lead to some pretty long and complicated command lines.
There are many ways to remedy this. See section 6 for ways to
minimize the command line options. The most complex command line
would be as follows:
SOURCE -n -N4 file.pas -c -b *.c -h2 *.dat -n-
This line contains global options and three file specifications
each giving their own local options. You will not normally have
such lines, but the power is there to use.
5 SOURCE Options
Page 5
SOURCE
What follows is a list of all the command line options that
SOURCE recognizes. These options may be specified as global or
local options on the command line (unless indicated otherwise).
They may also appear in the SOURCE.CFG file to define default
options for those options you wish to have in effect each time
you run SOURCE. See section 6 for more on the SOURCE.CFG file.
All options are case sensitive so do not run SOURCE with your
caps lock on.
Conventions used below:
[x] Square brackets indicate optional items. There
may not be a space between the option and the
parameter if specified. Example:
n[-] may entered as n or n-.
{x|y} Curly braces containing a list of choices
separated with a vertical bar indicate that you
must select one of the options available for that
item. There may not be a space between the option
and the chosen parameter. Example:
a{a|o|r} allows aa, ao, or ar.
"text" Quotes indicate that you must enter a text string.
You do not have to type the double quotes unless
the string contains spaces. There may be a space
between the option and the string. Example:
z "list" allows:
z.exe.obj <== No spaces
z".exe.obj" <== Quotes optional, no spaces
z".exe .obj" <==Quotes required, spaces
z .exe.obj
z ".exe.obj"
z ".exe .obj"
Not allowed would be:
z .exe .obj
because the parameter contains a space and must be
enclosed in quotes.
# A pound symbol indicates that you must enter a
number after the option. Numbers may be made up
of the 10 numeric digits and minus for negative
numbers. There may not be a space between the
option and the number. Example:
w# allows w1, w2, w3, etc.
h# allows h-1, h2, h0, etc.
Page 6
SOURCE
Option Description
? Help. The '?' option displays a quick command
summary showing all the available options and
their current defaults. Running SOURCE with no
options simply shows the command line syntax and
the '-?' option.
a{a|o|r} Append/Overwrite. The 'a' option describes the
action SOURCE will take when redirecting the
output to a file and the file already exists. See
the 'r' option for more on redirecting the output.
When the 'a' option is followed by an 'a', SOURCE
will automatically append the new output to the
previous contents of the file. When followed by
an 'o', SOURCE will automatically overwrite the
old contents of the file and leave only the new
output. When followed by an 'r', SOURCE will
interactively prompt you for the action to take.
You may specify 'append', 'overwrite', enter a
different file, or quit SOURCE. Default is 'ar',
request.
b[-] Block Grouping. The 'b' option sets whether block
grouping is turned on or not. The 'b' may be
followed by '-'. The 'b' option alone turns on
block grouping, the minus turns it off. For this
option to work, SOURCE must know what language the
file is written in. This is done by using the
filename extension as defined in the SOURCE.LNG
file or the 'x' option may be used to force a
specific language. The lines used for block
grouping may be drawn using either standard ASCII
characters or the IBM line drawing characters.
See the 'g' option to set how the lines are drawn.
Default is 'b', block grouping on.
Below is some sample C code with block grouping
turned on:
while (x < 10)
┌{
│if (a < b)
│ ┌{
│ │puts("Hello");
│ └}
│else
│ ┌{
│ │puts("Goodbye");
│ └}
│x++;
└}
Page 7
SOURCE
The above also assumes the 'g' option is on. With
the 'g' option off, the same code looks as
follows:
while (x < 10)
+{
|if (a < b)
| +{
| |puts("Hello");
| +}
|else
| +{
| |puts("Goodbye");
| +}
|x++;
+}
B# Banner. The 'B' option allows you to print a
banner before and/or after each file. The banner
contains the filename and extension in BIG
letters. The 'B' must be followed by a number
from 0 to 3. 0 means no banner at all. 1 means a
banner only before the file. 2 means a banner
only after the file. 3 means a banner before and
after the file. Default is 'B3', print banner
before and after.
c[-] Comment Highlighting. The 'c' option sets whether
comments within your programming code are
highlighted or not. The 'c' may be followed by
'-'. The 'c' option alone turns on highlighting,
the minus turns off it off. For this option to
work, SOURCE must know what language the file is
written in. This is done by using the filename
extension as defined in the SOURCE.LNG file or the
'x' option may be used to force a specific
language. The highlighting method used is as
defined in the SOURCE.PRT file for the selected
pitch. Default is 'c', highlighted comments on.
d "printer" Select Printer. The 'd' option specifies which
printer definition in the SOURCE.PRT file SOURCE
should use when printing out files. The 'd' must
be followed by the printer name. The name
specified is not case sensitive. If you only have
one printer connected to your computer you will
not need to use this option.
If you have multiple printers connected to
different ports, you can specify this option at
the command line when you are using a printer
other than the default. If this is the case, you
will also need to use the 'r' option to specify
the port the printer is connected to. If you use
different printers often, you may wish to define a
Page 8
SOURCE
named configuration in the SOURCE.CFG file for
each printer. Then all you need to specify on the
command line is the 'u' option. See the 'u'
option for more details on using named
configurations. The default printer is selected
by the user the first time SOURCE is run or by
modifying the SOURCE.PRT file. See section 7 for
more on SOURCE.PRT.
e[-] Escape Codes. The 'e' option sets whether printer
escape codes are output along with your text or
not. Normally you would want this left on so your
printer will print the file properly. Turning
this option off would typically be used when
redirecting output to a file when you would not
want the escape codes embedded in the target file.
The 'e' may be followed by '-'. The 'e' option
alone causes the codes to be printed, the minus
prevents the codes. Default is 'e', codes
printed.
f# Final Line. The 'f' option allows you to specify
the final line number of the file to print out.
This would be used to print only a desired block
of code instead of having to print the entire
file. The 'f' must be followed by a positive
number. Specifying zero means the last physical
line. This option may not be used with the 'F' or
'I' options unless set to zero. Default is 'f0',
print through last line.
F# Final Page. The 'F' option allows you to specify
the number of the final page of the file to print
out. This would be used to print only a block of
code, or part of a page range, instead of printing
out the entire file. The 'F' must be followed by
a positive number. Specifying zero means the last
physical page. This option may not be used with
the 'f' or 'i' options unless set to zero.
Default is 'F0', print through last page.
g[-] Graphics. The 'g' option determines how the block
group lines are printed (see option 'b' for more
on block grouping). When the option is on, the
lines will be printed using the IBM line drawing
characters. With the option off, simple ASCII
characters will be used. If your printer cannot
print the extended IBM character set then turn
this off. If your printer can print the lines
then set this to on. You may need to send a
special code to your printer to select the IBM
extended character set. To do so, place the
proper printer codes in the 'Init' record in the
SOURCE.PRT file for your printer. Default is
'g-', print using standard ASCII.
Page 9
SOURCE
h# Header Page. The 'h' option is used to specify
when to print the page header or footer. The 'h'
must be followed by a number. Zero means no
header or footer will be printed. A one means to
print the header only on the first page. Any
value of two or more will result in the header
being printed on all pages. To cause the header
to be printed at the bottom of the page (now a
footer), specify a negative number. Negative one
means to print a footer only on the first page.
Any number of -2 or less (-100 etc.) will cause
the footer to be placed on all pages. Page
headers and footers are underlined and printed in
10 pitch regardless of the pitch selected for the
rest of the file. The contents of the header are
user definable by using the 'H' option. Default
is 'h2', header on all pages.
H "header" Header Definition. The 'H' option is used to
define the contents of the header or footer. The
definition consists of literal text and escape
codes. Since the definition will likely contain
literal spaces, remember to enclose the definition
within double quotes. The escape commands are
case sensitive and literal text will be shown as
entered. The escape sequences are described here:
&fn Current filename and extension. The
filename is shown in uppercase. No path
is displayed.
&fd#c File creation date in specified format
where # is 1 to 5 and c is the delimiter
character ('/', ',', or '.').
&ft#c File creation time in specified format
where # is 1 to 4 and c is the delimiter
character (':', ',', or '.').
&cd#c Current date in specified format where #
is 1 to 5 and c is the delimiter
character ('/', ',', or '.').
&ct#c Current time in specified format where #
is 1 to 4 and c is the delimiter
character (':', ',', or '.').
&pn# Current page number in specified format
where # is the number of digits the page
number will take up. The value must be
in the range 1 to 9. The page number
will be left padded with spaces. If you
prefer zeros instead, precede the number
with a zero. Example: &pn03.
&li Initial line number on page.
&lf Final line number on page.
&h+ Turn on highlighting (using 10 high).
&h- Turn off highlighting (using 10 high).
&jl Left justify text.
&jc Center justify text.
Page 10
SOURCE
&jr Right justify text.
&& Prints a literal ampersand character.
Date formats:
1) mm dd yy ex. &fd1/ 07/31/92
2) dd mm yy ex. &cd2. 31.07.92
3) yy mm dd ex. &cd3, 92,07,31
4) dd Mmm yy ex. &fd4- 31-Jul-92
5) Month dd yyyy ex. &cd5, July 31, 1992
Time formats:
1) hh mm ss ex. &ct1: 15:45:21
2) hh mm ex. &ft2. 15.45
3) hh mm ss am ex. &ft3, 03,45,21 pm
4) hh mm am ex. &cd4: 03:45 pm
Example header definition:
'&h+File:&h- &fn&jr&h+Page:&h- &pn03'
This definition results in the following text:
File: filename.ext Page: 001
where the text 'File:' and 'Page:' are
highlighted, 'filename.ext' is the actual filename
of the file, and the page number is right
justified on the page. Default is "File: ",
filename, file date, file time, "Printed: ",
date, time, "Page: ", page number.
i# Initial Line. The 'i' option allows you to
specify the initial line number of the file to
output. This would be used to print only a block
of code instead of the whole file. The 'i' must
be followed by a positive number. Specifying zero
means the first physical line. It is likely that
'i' would be used in conjunction with the 'f'
option to print a specific range of text starting
and finishing at the line numbers chosen. This
option may not be used with the 'F' or 'I' options
unless set to zero. Default is 'i0', the first
line.
I# Initial Page. The 'I' option allows you to
specify the final page number of the file to
output. This would be used to print only a block
of code instead of the whole file. The 'I' must
be followed by a positive number. Specifying zero
means the first physical page. It is likely that
'I' would be used in conjunction with the 'F'
option to print a specific range of text starting
and finishing at the page numbers chosen. This
option may not be used with the 'f' or 'i' options
Page 11
SOURCE
unless set to zero. Default is 'I0', the first
page.
k[-] Highlighted Keywords. The 'k' option sets whether
keywords within your programming code are
highlighted or not. The 'k' may be followed by
'-'. The 'k' option alone turns on highlighting,
the minus turns it off. Only those words listed
in the "keyword" section of a language definition
are highlighted. For this option to work, SOURCE
must know what language the file is written in.
This is done by using the filename extension as
defined in the SOURCE.LNG file or the 'x' option
may be used to force a specific language. The
highlighting method used is as defined in the
SOURCE.PRT file for the selected pitch. Default
is 'k', highlighted keywords on.
l{6|8} Line Spacing. The 'l' option specifies the number
of lines per inch to print. The 'l' must be
followed by a 6 or an 8. Ensure that the proper
printer codes have been defined in the SOURCE.PRT
file for the eight lines per inch option to work.
Default is 'l6', six lines per inch.
m Shareware Message. The 'm' option causes a full
screen message to display about registering
SOURCE. This command is only recognized if in
SOURCE.CFG or as a global command line option.
n[-] Line Numbering. The 'n' option is used to specify
whether line numbers will be shown or not. Line
numbers are shown in the format specified in the
'N' option. The 'n' may be followed by '-'. The
'n' option alone turns on line numbering, the
minus turns it off. Default is 'n', line
numbering on.
N "beg#end" Line Number Format. The 'N' option specifies the
size and format of line numbers. The value of #
must be a number between 1 and 9. The terms "beg"
and "end" represent literal text that may be shown
before and after the line numbers. For example,
if you want four digit line numbers within square
brackets, you would specify the option as 'N[4]'.
This would result in [ 1], [ 2], etc., being
printed. Another example would be if you wanted
to specify 'N04:', which is the default, and this
would result in the line numbers being printed as
0001:, 0002:, and so on.
The line numbers are left padded with spaces. If
you prefer the number to be left padded with
zeros, precede the number with a zero. For
example: 'N4' will cause 1, 2, entering
Page 12
SOURCE
'N04' will cause 0001, 0002, etc. Both the
'begin' and 'end' text are optional. If there is
no 'end' text, the source code will be adjacent to
the line number. To avoid this, you may wish to
specify 'N"4 "'. The space inside the double
quotes will print after each line number.
Specifying a value for the number of digits that
is too small for the number of lines in the file
to be printed will result in the line numbers
wrapping around. For example, if you specify N01
and have 19 lines, line 10 would show up as 00,
and line 11 would become 01. This wrapping holds
true for any size specified. If your code
typically has less than 1000 lines, specify 3 for
the value of #, less than 10,000 lines, specify 4.
The default is 'N04:' which will produce 0001:,
0002:, etc.
o{l|p} Page Orientation. The 'o' option specifies the
page orientation. This will probably only work on
laser printers since most dot matrix printers
cannot print in landscape. The 'o' must be
followed by 'l' or 'p'. The 'l' indicates
landscape (sideways) printing and the 'p' is
portrait (normal). The landscape option requires
that the 'landscape' field be filled in in the
SOURCE.PRT file. Default is 'op', portrait.
p{p|e|c} Pitch. The 'p' option indicates the character
pitch to print the files in. The 'p' must be
followed by 'p' (pica or 10 cpi), 'e' (elite or 12
cpi), or 'c' (compressed using your printers
compressed value, usually 15, 16.666, or 17). If
your printer allows large pitch sizes such as 5
cpi, you could also use the compressed setting for
this. See section 7 for more on setting the
compressed pitch value. Default is 'pp', pica.
q[-] Page Count Query. The 'q' option causes SOURCE to
pre-scan each file and return the number of lines
in the file and how many pages (excluding any
banner pages) are required to print it based on
all other print options. You are then asked to
confirm whether to print the file or not.
Pressing 'Y' or 'y' will cause the file to be
printed. Any other keystroke will prevent the
file from being printed. Pressing the [Esc] key
will cause SOURCE to terminate. The 'q' may be
followed by '-'. The 'q' option alone turns on
the print statistics, the minus turns it off.
Turning on the 'q' option automatically turns on
the 'v' (print verification) option. Default is
'q', show page count.
Page 13
SOURCE
r "output" Redirect. The 'r' option allows you to redirect
the output to a file or other device such as the
screen or another printer port. The 'r' must be
followed by a filename or device name. The file
or device name is not case sensitive. Example
devices would be "LPT1", "PRN", or "COM2". You
may even specify "CON" to send the output to the
screen. When specifying a file, enter as much of
the full path name as is needed. You may specify
another drive or directory. No wildcards are
allowed. If the specified file already exists,
SOURCE will act as specified by the 'a' option.
Default is 'r lpt1', output to printer port one.
s{1|2} Column Count. The 's' option specifies the number
of columns to print per page. The 's' must be
followed by a 1 or a 2. It is recommended that
compressed landscape printing be used with two
columns. Using two columns in 10 pitch, portrait
print, leads to some difficult to read output.
Default is 's1', one column per page.
S[-] Show Column Separator. The 'S' option is used in
conjunction with the 's' option. When you specify
more than one column, the columns are separated by
a vertical line. The 'S' option allows you to
tell SOURCE whether to display this vertical line
or not. The 'S' may be followed by '-'. The 'S'
alone turns the line on, the minus turns it off.
Default is 'S', line on.
t# Tab Stop Size. The 't' option allows you to
specify how many spaces a tab character should be
printed as. The 't' must be followed by a number
from 0 to 8. Specifying zero is equivalent to
having all tabs removed from the file. Default is
't8', eight spaces per tab stop.
u "name" Use Named Configuration. The 'u' option is used
to specify a named configuration from within the
SOURCE.CFG file. See section 6.2 for more on
named configurations. The 'u' must be followed by
a configuration name that has been defined in
SOURCE.CFG. The name is not case sensitive. No
default.
v[-] Print Verification. The 'v' option is used to ask
the user to confirm the printing of each file.
This would most likely be used in conjunction with
wildcards in the filename. For example, you want
to print all but one or two files in a directory.
Specify "*.*/v" on the command line to select all
the files. SOURCE will then ask you to confirm
the printing of each file. Just press 'Y' or 'y'
for the ones you want to print. Any other key
Page 14
SOURCE
stroke other than 'Y' or 'y' will be the same as
no. Pressing the [Esc] key will cause SOURCE to
terminate. The 'v' option is automatically turned
on when the 'q' option is turned on. The 'v'
option may be followed by '-'. The 'v' option
alone turns on the print verify, the minus turns
it off. Default is 'v-', do not ask about each
file.
w# Whitespace. The 'w' option is used to specify the
number of blank lines printed between the
header/footer and the first/last line of text of
the file on the page. The 'w' must be followed by
a value between 0 and 9. Specifying zero will
result in no blank space. See the 'h' and 'H'
options for more on user definable headers and
footers. Default is 'w1', one line.
x "language" Force Language. The 'x' option allows you to tell
SOURCE the language of a file regardless of its
extension. This option is useful only when using
the 'b', 'c', or 'k' options (block grouping and
comment or keyword highlighting). The 'x' must be
followed by a language name defined in SOURCE.LNG.
The name is not case sensitive. For example, if
you have a file with a 'bak' extension that really
is a Pascal program, by following the file with
the '-xPascal' option, SOURCE will treat the file
as Pascal code so comments and blocks print
correctly. This assumes that there is a
definition for 'Pascal' in the SOURCE.LNG file.
Default is none (use extension).
y[-] Sound. The 'y' option determines whether the
speaker will emit a bell or buzz sound when
prompts or errors occur. This option is not
recognized as a local option. The 'y' may be
followed by '-'. The 'y' option alone turns on
sound, the minus turns them off. Default is 'y-',
sound off.
z "list" Ignore These Extensions. The 'z' option is used
to tell SOURCE what files to ignore during
wildcard expansion. For example, if you run
SOURCE with "*.*", you will have a mess at your
printer when it tries to print executables and
object code! You could specify the 'v' option
each time and say no to files with ".exe" or
".obj" extensions, or you could use the 'z' option
to tell SOURCE to automatically ignore the ".exe"
and ".obj" extensions every time. The syntax for
the 'z' option is the list of extensions
(including the period) between a pair of double
quotes (if you place a space between each). The
list is not case sensitive. To continue the
Page 15
SOURCE
example, specify the 'z' option as 'z ".exe
.obj"'. You may specify as many extensions as you
like as long as all are specified with one 'z'
option. Using two 'z' options will cause the
first one to be ignored. Default is 'z ".exe .com
.sys .obj"'.
6 SOURCE.CFG
The SOURCE.CFG file is used to store groups of configuration
options that may be used by SOURCE. Among these groups are a set
of default options. These default options are seen by running
SOURCE with the '-?' global option. These default options, as
initially defined, are actually the same defaults hard coded
within SOURCE itself.
6.1 SOURCE.CFG Location
SOURCE.CFG is actually not needed. If SOURCE can not find
SOURCE.CFG, it will fall back on the built in defaults and
continue to work fine. SOURCE.CFG can be located in many
different places. By default, you should place a copy in the
same directory as SOURCE.EXE (from now on referred to as the
SOURCE directory). With this setup, running SOURCE from any
directory will cause SOURCE to use the defaults defined in
SOURCE.CFG in the SOURCE directory.
In addition to placing SOURCE.CFG in the SOURCE directory, you
may also place other copies in any other directory you wish. For
example, you have a 'prog' directory on your hard disk. If you
place another copy of SOURCE.CFG in 'prog' and run SOURCE while
your default directory is 'prog', SOURCE will use the SOURCE.CFG
file in the 'prog' directory instead of the SOURCE directory. By
tailoring the SOURCE.CFG file to the files in 'prog', you can
minimize the amount of command line options you need to specify.
The whole point to allowing this kind of flexibility is that you
might be working on different projects that require different
printing styles. By placing tailored SOURCE.CFG files in the
different directories, you can easily accomplish the diverse
printing needs.
6.2 Named Configuration Options
If you have looked at the contents of SOURCE.CFG, you will notice
that there seems to be more than just defaults defined in there.
SOURCE.CFG can actually store up to fifty sets of configuration
options. The first of which (as supplied) is the default
options. These different sets of options are referred to as
named configuration options. The supplied defaults are actually
a named configuration option titled 'Default'. SOURCE
automatically looks for 'Default' and loads the options in if
found. In addition to the 'Default' setup, you may define 49
more of your own design. If for some reason you do not want the
defaults loaded, rename 'Default' to something else. You may
Page 16
SOURCE
then refer to the defaults explicitly by using the 'u' option on
the command line. See section 5 for more information on
selecting named configurations from the command line using the
'u' option.
The idea behind named configurations allows you to define a
commonly used, but cumbersome, set of configuration options into
a simple, single command line option. A common use for them
might be on a LAN where each user has their own favorite set of
defaults. The SOURCE.CFG file could contain one set for each
user using their name or initials to name the options. On the
command line, simply specify "-u name" and all the options
defined as "name" in SOURCE.CFG will be used. Another
circumstance could be to use named options when you are using
SOURCE with multiple printers. If you have "printer1" on "lpt1"
and "printer2" on "com3", you could add two named configurations,
"p1" and "p2". "p1" would have '-d printer1 -r lpt1' and "p2"
would have '-d printer2 -r com3'. You could also add the 'g'
option if one printer could print the IBM line drawing characters
and one could not. Typing 'source -u p1' at the command line is
easier than 'source -d printer1 -r lpt1 -g'. One other
possibility would be if you wished to print source code in
different languages in different formats.
The named set of options may also contain a 'u' option. This
allows for nested definitions. As an example, let's say you have
two named configurations, "name1" and "name2". If "name1"
contains '-u name2', "name1" will pull in the options defined in
"name2". The result of using "name1" will be all the options in
"name1" and all the options in "name2" being used.
6.3 SOURCE.CFG Format
The format of the SOURCE.CFG file is simple. A named
configuration begins with the key word "begin" followed by a
name. This name can contain any characters you can type at the
DOS prompt. I recommend descriptive names that indicate what the
options represent. Spaces are not allowed in the name. The only
limit is the full name must be 20 characters or less. After the
"begin" line, enter any set of options you like. There are two
ways of entering the options. The easiest to read is to place
one command per line. Each command must be preceded by a hyphen.
Example:
-t3
-pp
The second method allows more than one command per line. This is
identical to global options on the command line. Simply separate
the commands by at least one space. Again, each command must be
preceded by a hyphen. Example:
-l8 -s2
Page 17
SOURCE
You may also enter the commands using any combination of the two
methods. Example:
-q -i5 -f100
-z ".exe .obj .sys"
After all options have been specified, enter the key word "end"
on a line by itself to signal the end of the named definition.
You may define up to 20 named configurations. A full definition
would look as follows:
begin Test
-q -F2
end
6.4 Commenting SOURCE.CFG
You may place comments in the SOURCE.CFG file by beginning a line
with a semicolon ( ; ). All text on that line will be ignored by
SOURCE. Do not place comments on lines with options. The
comment must go on a line by itself. Example:
; This is a valid comment
-b -c ; This is not a valid comment - must be on own line
6.5 Modifying SOURCE.CFG
I recommend you modify the 'Default' named option in SOURCE.CFG
to suit your most common needs. This will result in having to
specify little on the command line other than the filenames to
print. If you need to print a file slightly different one time,
specify only the options required for the difference. Add other
named options for other commonly used configurations like those
mentioned above. This allows you to use very different print
formats with minimal command line typing.
One common change to the defaults would be to specify a different
printer port. Initially, SOURCE assumes printer port one, LPT1:.
If you are using a serial printer on a COM port or another
printer port, change the default setting for the 'r' option.
Replace the word 'lpt1' with 'com1' or 'lpt2' or whatever is
appropriate for you.
7 SOURCE.PRT
This file allows you to define any printer configuration you may
have. Only one copy of SOURCE.PRT is used and this must reside
in the same directory as SOURCE.EXE. This file is required and
SOURCE will not run if not found. SOURCE.PRT can contain printer
definitions for up to 20 different printers, though I doubt you
will ever need that many. Once you define your printer, you can
delete all other definitions if you like. However, if you have
more than one printer, leave all the necessary definitions.
7.1 Default Printer
Page 18
SOURCE
If you have more than one printer defined, you must make one the
default. This can be done automatically the first time you run
SOURCE. If you would like to change that default at a later
time, you must manually edit the SOURCE.PRT file. To make a
printer the default, place the keyword "default" after the
printer name. Example: 'begin HPLJII+ default'. If you specify
more than one default, the last one will be chosen. Remember you
can use the 'd' option to select a printer other than the default
if needed. If you only have one printer defined in SOURCE.PRT
you do not need to specify the keyword "default".
7.2 SOURCE.PRT Format
Similar to SOURCE.CFG, each definition in SOURCE.PRT begins with
the keyword 'begin' followed by a name. The name may be made up
of any characters you can type at the DOS prompt up to 20
characters. The name may not contain spaces. The printer
definition ends with the keyword 'end' on a line by itself. In
between are the lines specifying your printer setup. The syntax
of each line is a field name, a colon, and the value you enter
for that field. Each line can contain only one field.
For those fields that require a printer escape sequence, you can
enter the codes as literal characters or by entering the decimal
value in square brackets. You may also enter the code as a
combination of both. For example, the reset code on a Hewlett
Packard Laser Jet is [Esc]E. You might not be able to enter a
literal escape character in your editor. The solution is to use
the decimal value in square brackets. [Esc] is ASCII value 27.
The 'E' can be entered literally. The two codes together would
be entered into the reset field as: [27]E. Since the square
brackets are being used as special characters by SOURCE, you may
not enter them as literal characters in the printer code. If
your code needs the characters '[' or ']', enter the decimal
value in square brackets. The left bracket '[' becomes [91] and
the right bracket ']' becomes [93]. The value inside the bracket
must be a decimal number from 1 to 255.
A list of the fields and a description of each is as follows:
page width: This field is the physical page width in inches.
This will typically be 8.5 for standard letter
sized paper. If you are using wide computer
paper, this could be 14. This field is required.
page length: This field is the physical page length in inches.
Normal letter size paper would be 11. Legal size
paper would be 14. This field is required.
top margin: Indicates the top margin in inches. The first
printed line will be placed this far from the top
of the page. A standard half inch margin would be
.5. This value must be greater than or equal to
the top edge. This field is required.
Page 19
SOURCE
bottom margin: Indicates the bottom margin in inches. The last
line printed will be this far from the bottom of
the page. This value must be greater than or
equal to the bottom edge. This field is required.
left margin: This is the left margin in inches. The left most
characters will be this far from the left edge of
the paper. This value must be greater than or
equal to the left edge. This field is required.
right margin: This is the right margin in inches. The right
most characters will be this far from the right
edge of the paper. This value must be greater
than or equal to the right edge. This field is
required.
top edge: The top edge is used to define the physical
limitation of the printer to print at the top of
the page. Laser printers typically are set with a
half inch limit at the top. By entering .5 here,
the margin specified in 'top margin' will come out
correctly. This field is required.
bottom edge: The bottom edge is used to define the physical
limitation of the printer to print at the bottom
of the page. Laser printers typically are set
with a half inch limit at the bottom. By entering
.5 here, the margin specified in 'bottom margin'
will come out correctly. This field is required.
left edge: The left edge is used to define the physical
limitation of the printer to print at the left
edge of the page. Laser printers typically cannot
print on the first quarter inch of the left edge.
By entering .25 here, the margin specified in
'left margin' will come out correctly. The exact
value entered may be slightly different. Try .2
or .3. Experiment with the proper value to set
your printer up correctly. This field is
required.
right edge: The right edge is used to define the physical
limitation of the printer to print at the right
edge of the page. Laser printers typically cannot
print on the last quarter inch of the right edge.
By entering .25 here, the margin specified in
'right margin' will come out correctly. The exact
value entered may be slightly different. Try .2
or .3. Experiment with the proper value to set
your printer up correctly. This field is
required.
10 pitch: This field is used to enter the escape sequence
used by your printer to print text at ten
Page 20
SOURCE
characters per inch. Enter the sequence exactly
as shown in your printer manual including case.
12 pitch: This field is used to enter the escape sequence
used by your printer to print text at 12
characters per inch. Enter the sequence exactly
as shown in your printer manual including case.
This field is required to use this feature.
compressed: This field is used to enter the escape sequence
used by your printer to print text in compressed
mode. This is usually 15, 16.66, or 17. You may
even enter the code for enlarged print such as 5
cpi. Enter the sequence exactly as shown in your
printer manual including case. This field is
required to use this feature.
comp size: This field is used to specify the characters per
inch your printer will print while in compressed
mode. Typically this value will be 15, 16.666, or
17 (or even 5 for enlarged print). This field is
required to print in compressed mode.
underline on: This is the printer escape sequence for turning
underlining on. This is used only by the page
header/footer. This field is required to use this
feature. If you do not want the header
underlined, leave this field blank.
underline off: This is the printer escape sequence for turning
underlining off. This is used only by the page
header/footer. This field is required to use this
feature. If you do not want the header
underlined, leave this field blank.
10 high on: This is the printer escape sequence used to print
comments when the 'c' option is used and the 'p'
option was set to 10. This code could be almost
anything your printer can do. Examples are bold,
underline, and italic. DO NOT use a code that
prints in a different size font like expanded or
double height. This will cause the file to print
incorrectly. Whatever code is used must not
change the current print size. This field is
required to use this feature.
10 high off: This is the printer escape sequence used to turn
off the code used by '10 high on'. This field is
required to use this feature.
12 high on: This is the printer escape sequence used to print
comments when the 'c' option is used and the 'p'
option was set to 12. This code could be almost
anything your printer can do. Examples are bold,
underline, and italic. DO NOT use a code that
Page 21
SOURCE
prints in a different size font like expanded or
double height. This will cause the file to print
incorrectly. What ever code is used must not
change the current print size. This field is
required to use this feature.
12 high off: This is the printer escape sequence used to turn
off the code used by '12 high on'. This field is
required to use this feature.
comp high on: This is the printer escape sequence used to print
comments when the 'c' option is used and the 'p'
option was set to your compressed value. This
code could be almost anything your printer can do.
Examples are bold, underline, and italic. DO NOT
use a code that prints in a different size font
like expanded or double height. This will cause
the file to print incorrectly. What ever code is
used must not change the current print size. This
field is required to use this feature.
comp high off: This is the printer escape sequence used to turn
off the code used by 'comp high on'. This field
is required to use this feature.
init: This code is sent to the printer before the first
file is printed. This should contain all required
printer initialization codes to setup your
printer. Examples would be the initialize printer
code, character set selection (not pitch size),
and print quality (draft, NLQ, etc.). There
should be nothing in here for selecting pitch or
page orientation since this will be done using the
other codes specific to those settings. This is
not required.
reset: This code is sent to the printer after the last
file is sent. This can be blank. This may be
used to place the printer back into the mode it
was prior to the "Init" code being sent. This is
not required.
portrait: This is the code sent to the printer to set the
paper orientation to portrait - the usual way the
page is set. This only applies to laser printers
since dot matrix printers cannot print any other
way using straight text printing (as opposed to
graphics). This must be filled in if your printer
supports portrait and landscape printing.
landscape: This is the code sent to the printer to set the
paper orientation to landscape - sideways
printing. This only applies to laser printers
since dot matrix printers cannot print landscape
Page 22
SOURCE
without using graphics. This must be filled in to
make use of the landscape printing feature.
6 lpi: This code is used to print the file at six lines
per inch. This is the usual default for all
printers. If your printer does not support eight
lines per inch than you may leave this blank,
otherwise this is required.
8 lpi: This code is used to print the file at eight lines
per inch. If your printer does not support eight
lines per inch than you may leave this blank,
otherwise this is required to use the feature.
There are many relationships between the values placed in the
above fields. The sum of the top and bottom margins must be less
than the page length. The sum of the left and right margins must
be less than the page width. All margins must be greater than or
equal to their corresponding edge. If you only have 10 pitch
printing, you may leave all three pitch codes blank. If you can
only print at six lines per inch, you may leave both the six and
eight lines per inch codes blank.
Certain combinations of print options do not work together on
some printers. For example, Hewlett Packard laser jet printers
will not print bold or italic while in compressed print. This is
why there are separate highlight codes for the different pitch
sizes. This allows you to specify bold or italic for 10 and 12
pitch and underlining for compressed printing.
7.3 Modifying Your Printer
As delivered, the SOURCE.PRT file has only a few basic printers
within it. These may not fit your printer completely if at all.
To take full advantage of your printer's abilities, you can edit
SOURCE.PRT by placing an entry for your printer within it. To do
so, either reuse an existing entry that is similar to your
printer or copy the 'Generic' definition and rename the copy to
match your printer name. Once you have this done, open up your
printer's reference manual to the section that describes all the
features and their associated escape sequences. Enter the codes
you need into the proper fields and you will be ready to go. It
may take some trial and error to get everything perfect, but it
can be done.
8 SOURCE.LNG
SOURCE.LNG contains the definitions for the language support
features of SOURCE. The two options are comment highlighting and
code block grouping or tracing. The SOURCE.LNG file details what
makes a comment, a literal string and character, and what
represents a code block.
8.1 SOURCE.LNG Location
Page 23
SOURCE
SOURCE.LNG is not a required file. If SOURCE can not find
SOURCE.LNG, it will ignore the use of the b and c options and
continue to work fine. SOURCE.LNG can actually be located in
many different places. By default, you should place a copy in
the same directory as SOURCE.EXE (from now on referred to as the
SOURCE directory). With this setup, running SOURCE from any
directory will cause SOURCE to use the definitions in the
SOURCE.LNG in the SOURCE directory.
In addition to placing SOURCE.LNG in the SOURCE directory, you
may also place other copies in any other directory you wish. For
example, you have a 'prog' directory on your hard disk. If you
place another copy of SOURCE.LNG in 'prog' and run SOURCE while
your default directory is 'prog', SOURCE will use the SOURCE.LNG
file in the 'prog' directory instead of the SOURCE directory. By
tailoring the SOURCE.LNG file to the files in 'prog', you can
work with different dialects of the same language.
The whole point to allowing this kind of flexibility is that you
might be working on different projects that require different
language definitions. By placing tailored SOURCE.LNG files in
the different directories, you can easily accomplish the diverse
needs.
8.2 SOURCE.LNG Format
The format of SOURCE.LNG is similar to the other support files.
You begin a language definition with the keyword 'beginlang'
followed first by the name of the language and then a list of
filename extensions associated with the language. The language
name can be any characters you can type at the DOS prompt. The
name cannot contain spaces and may be up to 20 characters long.
The list of extensions are used to tell SOURCE to treat any file
with the given extension as a file of that language. An example
would be: 'beginlang C .c .h'. This defines a language called
"C". Any file with the extension ".c" or ".h" would be treated
as a "C" file. You may specify up to 10 extensions per language.
The second line of the definition is a list of legal characters
that may be found in identifiers and keywords. Identifiers
include variables and labels within a program. These characters
are used to tell SOURCE how to discern between to words in a
program. Most languages allow letter and numbers. Some also
allow some puncuation like underscores. See your language
reference. It should detail the allowable characters. The list
of characters must be contiguous and on one line with no spaces.
You only need to specify either lower or upper case letters, not
both.
The language definition is completed with the keyword 'endlang'
on a line by itself. This may be followed by the keyword 'case'
to indicate that the language is case sensitive and/or 'part' to
indicate that keywords only need to match partially. This is
explained in detail below. Any other keywords, or none at all,
indicate that the language is case independent and keywords
Page 24
SOURCE
require a full match. Example: 'endlang case' terminates the
language definition and specifies case dependency. 'endlang' or
'endlang nocase' indicate the end of a case independent language.
The SOURCE.LNG file may contain up to twenty language
definitions. You only need those for which you have use, so feel
free to delete unneeded languages from the supplied SOURCE.LNG
file.
8.3 Commenting SOURCE.LNG
You may place comments in the SOURCE.LNG file by beginning a line
with a semicolon (;). All text on that line will be ignored by
SOURCE. Do not place comments within a language definition, only
before the 'beginlang' line or after the 'endlang' line.
8.4 Defining Language Specific Features
8.4.1 Comments
After the 'beginlang' line, you specify how comments are defined.
This begins with the line ':comment:'. After the ':comment:'
line, you specify three lines. The first line is the begin
comment command, the second is the end comment command. The
third line contains a number from zero to 80. This number
indicates the column that the begin comment command must begin
in. A zero indicates that the comment may begin in any column.
An example for the 'C' language would be:
:comment:
/* <== Begin comment
*/ <== End comment
0 <== Comment may be in any column
You may specify more than one comment. For example, Turbo Pascal
allows the following:
:comment:
{
}
0
(*
*)
0
For languages such as BASIC where comments are terminated by the
end of line, specify the begin command on the first line and
leave the second line blank. Example:
:comment:
REM
<== This is a blank line
0
Page 25
SOURCE
One of the few examples of specifying a non-zero column number
would be for FORTRAN. Comments in FORTRAN are specified by
placing a 'C' in column one. The definition for this would be:
:comment:
C <== Comments begin with a C
<== Terminated by end-of-line
1 <== C must be in column one
Since blank lines are interpreted as part of the syntax, you may
not leave blank lines within a language definition in the
SOURCE.LNG file unless it is required as above. You may define
up to 7 comment marker pairs per language.
8.4.2 String and Character Literals
After defining the comments, you define what makes up literal
strings and characters. This is done just like comments. You
begin with the line ':string:'. After this line, you enter two
lines per string or character. The first line contains the
delimiter used to begin and end a literal string or character
(typically a single or double quote). The second line specifies
an escape sequence. This is the sequence (usually one character)
used to allow the delimiter character to be used literally within
a string or as a character. 'C' is a good example of this.
Strings are set in double quotes. To place a double quote within
a string, you must precede the double quote with a backslash ("He
said \"Hello\""). The definition would be as follows:
:string:
" <== String Delimiter
\ <== Escape Sequence
Characters in 'C' are similar. Literal characters are defined by
single quotes. To assign a literal single quote in 'C', you
precede the literal quote with a backslash ('\''). The
definition would be:
:string:
' <== Character Delimiter
\ <== Escape Sequence
For languages such as Pascal where strings are defined by single
quotes and a literal single quote is specified by two single
quotes ('It''s mine'), simply place the following definition:
:string:
' <== String & Character Delimiter
' <== Escape Sequence
For languages such as BASIC which do not allow you to place the
string delimiter within the string, you would leave the second
line blank.
Page 26
SOURCE
You may declare up to five pairs of delimiters per language. The
full string definition for 'C' would be:
:string:
"
\
'
\
8.4.3 Blocks
After specifying the string definition, you must define what
commands make up blocks. The keywords defined here are used with
the 'b' option to allow block grouping to work. The definition
begins with the keyword ':block:'. Following are two lines per
block. The first line is the begin block command and the second
line is the end block command. For 'C', this is easy because all
blocks are marked the same. Blocks begin with a left curly brace
and end with a right curly brace. The definition would be:
:block:
{
}
For languages like Pascal, you may have numerous block pairs.
Example:
:block:
begin
end
record
end
case
end
repeat
until
For most languages, the keyword used to define a block must be
entered in its entirety. You can't specify
beg
...
end
in Pascal for example. You must enter the whole keyword. A
counter example to this is the dBase programming language. dBase
allows you to enter only the first four letters of each keyword.
A 'while' loop could be entered as:
do while do whil
... or ...
enddo endd
For SOURCE to work with a language such as this, you must specify
the "part" or "partial" keyword after the "endlang" keyword at
Page 27
SOURCE
the end of the language definition followed by the number of
characters needed. If SOURCE finds the 'part' keyword at the end
of a definition, comment and block keywords entered in SOURCE.LNG
for that language will be treated as the minimal text that must
be entered to be a valid keyword in the program. If the 'part'
keyword is not specified, SOURCE will treat the comment and block
keywords in SOURCE.LNG as the full keyword that must be found in
the file being printed.
8.4.4 Keywords
After specifying the block definition, you must define those
keywords that you would like highlighted when the 'k' option is
active. The definition begins with the keyword ':keyword:' and
is followed by one keyword per line. The keywords may have
spaces in them. The words may be entered in any order. You may
enter any words you like. The idea is to highlight reserved
words so you can pick out variables and function names easier.
If you have certain functions or other words you would like
highlighted, simply add them to the list. A partial list for 'C'
would be:
:keyword:
auto
break
case
char
const
continue
. . .
If the language is case dependant, ensure the keywords are
entered in the proper case. If case independant, the entered
case is irrelevant. If the language supports partial keyword
matching (like dBASE), you must enter the shortest portion of the
keyword that the language recognizes just as you did for the
'block' section. SOURCE will highlight the entire keyword found
in the program. For example, if you have the keyword 'endt'
(short for 'endtext' in dBASE) in the language definition, and
SOURCE finds the 'endtext' in the program, the entire 'endtext'
will be highlighted.
It is important that the keywords entered only contain those
characters entered on the second line of language definition. If
other characters are used, the keyword may not be highlighted
properly. You may define up to 400 keywords per language.
8.4.5 Complete Definition
Now that you have seen each part of the definition, here is a
full definition as it would appear in SOURCE.LNG for 'C'.
beginlang C .c .h
abcdefghijklmnopqrstuvwxyz0123456789_ <== Valid characters
:comment:
Page 28
SOURCE
/*
*/
0 <== Any column
:string:
"
\
'
\
:block:
{
}
:keyword:
auto
break
case
char
const
continue
. . . <== There are more, but you get the point
endlang case
For dBase, the full definition would be:
beginlang dbase .prg
:comment:
*
<== Comments end with end-of-line
0 <== Begin in any column
&&
<== Comments end with end-of-line
0
note
<== Comments end with end-of-line
0
:string:
"
<== No double quotes in strings
:block:
do case
endc <== Minimum required
do whil <== Minimum required
endd <== Minimum required
if
endi <== Minimum required
text
endt <== Minimum required
:keyword:
acce
addi
alia
all
all like
appe
appe from
. . . <== There are more, but you get the point
Page 29
SOURCE
endlang part 4
8.5 General Points
Some points to keep in mind when defining a language. If you
have more than one language with the same extension, SOURCE will
choose the first. To override this, you can use the 'x' option
on the command line to explicitly choose the language you really
need.
While defining a comment or a block, you may not define two or
more pairs that begin with the same keyword, regardless of the
ending keyword. However, you may define any number of pairs that
have the same ending keyword as long as the beginning keywords
are unique. This should never be a problem because two blocks
with the same beginning keyword would lead to a rather ambiguous
syntax.
When defining blocks for the language, be careful with statements
using variable syntax. A good example is the 'IF' statement in
some BASICs. The syntax can be:
1) IF condition THEN statement [ELSE statement]
or
2) IF condition THEN
statements
[ELSE
statements]
ENDIF
DO NOT specify in your block definitions 'IF' - 'ENDIF' because
if SOURCE encounters the first syntax, the line will never
terminate because it will not find the 'ENDIF'. Unfortunately,
there is no solution to this. The only downside is that you will
not get trace lines for your IF statements. If you know for a
fact that you did not use the first syntax, then go ahead and
specify the 'IF' - 'ENDIF' block.
9 Network Support
SOURCE currently has limited network support. The support
offered at this time allows you to define an environment variable
called "USER". SOURCE will determine the value of "USER" and
load the named configuration, from SOURCE.CFG, of the same name.
This configuration option will be used as the default set of
options instead of "Default".
This setup allows SOURCE to be installed on a network server.
Each user would add a line like:
set USER=<name>
Page 30
SOURCE
to their "autoexec.bat" file. The <name> would be a unique
identifier for that person. This could be a last name or
initials. The SOURCE.CFG file in the SOURCE directory would
contain a named configuration for each user on the network.
Care must be taken to limit write access to the common SOURCE.CFG
file. You may wish to allow only the network supervisor to
update this file to prevent problems with each user adding their
options. Data will get lost if two people try editing at the
same time.
If SOURCE cannot find a named configuration with the same name as
the value of "USER", SOURCE will fall back on the "Default" named
configuration.
Having the environment variable defined is slightly different
from using the '-u <name>' command line option. When using the
environment variable, the matching named configuration is used in
place of the default named configuration. When using the 'u'
option, the matching named configuration is loaded in addition to
the default named configuration.
10 Definition of Shareware
Shareware distribution gives users a chance to try software
before buying it. If you try a Shareware program and continue
using it, you are expected to register.
Copyright laws apply to both Shareware and commercial software,
and the copyright holder retains all rights, with a few specific
exceptions as stated below. Shareware authors are accomplished
programmers, just like commercial authors, and the programs are
of comparable quality. (In both cases, there are good programs
and bad ones!) The main difference is in the method of
distribution. The author specifically grants the right to copy
and distribute the software, either to all and sundry or to a
specific group. For example, some authors require written
permission before a commercial disk vendor may copy their
Shareware.
Shareware is a distribution method, not a type of software. You
should find software that suits your needs and pocketbook,
whether it's commercial or Shareware. The Shareware system makes
fitting your needs easier, because you can try before you buy.
And because the overhead is low, prices are low also. Shareware
has the ultimate money-back guarantee -- if you don't use the
product, you don't pay for it.
11 Disclaimer - Agreement For Trying SOURCE
Users of SOURCE must accept this disclaimer of warranty:
"SOURCE is supplied as is. The author disclaims all
warranties, expressed or implied, including, without
limitation, the warranties of merchantability and of
Page 31
SOURCE
fitness for any purpose. The author assumes no
liability for damages, direct or consequential, which
may result from the use of SOURCE."
SOURCE is a "shareware program" and is provided at no charge to
the user for evaluation. Feel free to share it with your
friends, but please do not give it away altered or as part of
another system. The essence of "user-supported" software is to
provide personal computer users with quality software without
high prices, and yet to provide incentive for programmers to
continue to develop new products. If you find this program
useful and find that you are using SOURCE and continue to use
SOURCE after a reasonable trial period, you must make a
registration payment to Rick Maddy.
The registration fee will license one copy for use on any one
computer at any one time. You must treat this software just like
a book. An example is that this software may be used by any
number of people and may be freely moved from one computer
location to another, so long as there is no possibility of it
being used at one location while it's being used at another.
Just as a book cannot be read by two different persons at the
same time. Site-License arrangements may be made by contacting
Rick Maddy.
You are encouraged to pass a copy of SOURCE along to your friends
for evaluation. Please encourage them to register their copy if
they find that they can use it. All registered users will
receive a copy of the latest version of SOURCE in your name,
printed documentation, a quick reference card, upgrade notices
and discounts, and customer support.
12 Registering
You may use SOURCE for a free 30 day trial period. If you
continue to use SOURCE after the 30 day trial period, you are
required to register your copy of SOURCE.
When you register SOURCE you will be sent a disk with the latest
version of SOURCE in your name, printed documentation, a quick
reference card, upgrade notices and discounts, and customer
support. The cost of registration is $20.00.
You can order directly from Rick Maddy by completing the
registration form and mailing it and a check to:
Rick Maddy
7111 Kurth Lane
Seabrook, MD 20706
The registration form is at the end of this document and in a
separate file called register.txt.
Page 32
SOURCE
If you have any questions or comments, feel free to call Rick
Maddy at (301) 794-8466 or leave a mail message on Compuserve at
76460,1601.
13 Future Enhancements
I have a few ideas for making SOURCE an even better utility.
Here is a brief list:
- Full screen interface to replace command line.
- Full screen programs for editing printer, language, and
configuration files.
- Windows 3.1 version.
- Optional log file of all printed files.
- Expanded file selection (i.e. date range).
- Print files in sorted order by name, size, date, etc.
- Expanded network/multi-user support.
I am open to any comments or suggestions for improvements or
additions to SOURCE. Please drop me a line.
14 Acknowledgements
I would like to thank the following people for all there help in
finishing this program:
- Scott Sidel for his help with making this program easier
to use and writing this documentation.
- Robert Harvey and William Moussiaux for beta testing
SOURCE.
- All the kind people who answered my questions about OS/2
on Compuserve.
Page 33
SOURCE REGISTRATION
Remit to: From:
Rick Maddy Name:__________________________________
7111 Kurth Lane Company:_______________________________
Seabrook, Md 20706 Street:________________________________
(301) 794-8466 City:__________________________________
State/Zip:_____________________________
Compuserve Id: Phone:_________________________________
76460, 1601
Name to register in:
(Up to 40 characters)
_______________________________________
Qty: Unit Price Total:
____ SOURCE Software $20.00 ________
Specify Disk Size:
_____ 5 1/4" _____ 3 1/2"
Current Version of Source:______________________________________
